<!DOCTYPE html>
<html>

  <head>
    <meta charset='utf-8' />
    <meta http-equiv="X-UA-Compatible" content="chrome=1" />
    <meta name="description" content="http-request : Java HTTP Request Library" />

    <link rel="stylesheet" type="text/css" media="screen" href="stylesheets/stylesheet.css">

    <title>http-request</title>
  </head>

  <body>

    <!-- HEADER -->
    <div id="header_wrap" class="outer">
        <header class="inner">
          <a id="forkme_banner" href="https://github.com/kevinsawicki/http-request">View on GitHub</a>

          <h1 id="project_title">http-request</h1>
          <h2 id="project_tagline">Java HTTP Request Library</h2>

            <section id="downloads">
              <a class="zip_download_link" href="https://github.com/kevinsawicki/http-request/zipball/master">Download this project as a .zip file</a>
              <a class="tar_download_link" href="https://github.com/kevinsawicki/http-request/tarball/master">Download this project as a tar.gz file</a>
            </section>
        </header>
    </div>

    <!-- MAIN CONTENT -->
    <div id="main_content_wrap" class="outer">
      <section id="main_content" class="inner">
        <h1>
<a name="http-request" class="anchor" href="#http-request"><span class="octicon octicon-link"></span></a>Http Request</h1>

<p>A simple convenience library for using a <a href="http://download.oracle.com/javase/6/docs/api/java/net/HttpURLConnection.html">HttpURLConnection</a>
to make requests and access the response.</p>

<h2>
<a name="usage" class="anchor" href="#usage"><span class="octicon octicon-link"></span></a>Usage</h2>

<p>The http-request library is available from <a href="http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22com.github.kevinsawicki%22%20AND%20a%3A%22http-request%22">Maven Central</a>.</p>

<div class="highlight"><pre><span class="nt">&lt;dependency&gt;</span>
  <span class="nt">&lt;groupId&gt;</span>com.github.kevinsawicki<span class="nt">&lt;/groupId&gt;</span>
  <span class="nt">&lt;artifactId&gt;</span>http-request<span class="nt">&lt;/artifactId&gt;</span>
  <span class="nt">&lt;version&gt;</span>5.4<span class="nt">&lt;/version&gt;</span>
<span class="nt">&lt;/dependency&gt;</span>
</pre></div>

<p>Javadocs are available <a href="http://kevinsawicki.github.com/http-request/apidocs/index.html">here</a>.</p>

<h2>
<a name="faq" class="anchor" href="#faq"><span class="octicon octicon-link"></span></a>FAQ</h2>

<h3>
<a name="who-uses-this" class="anchor" href="#who-uses-this"><span class="octicon octicon-link"></span></a>Who uses this?</h3>

<p>See <a href="https://github.com/kevinsawicki/http-request/wiki/Used-By">here</a> for a
list of known projects using this library.</p>

<h3>
<a name="why-was-this-written" class="anchor" href="#why-was-this-written"><span class="octicon octicon-link"></span></a>Why was this written?</h3>

<p>This library was written to make HTTP requests simple and easy when using a <code>HttpURLConnection</code>.</p>

<p>Libraries like <a href="http://hc.apache.org">Apache HttpComponents</a> are great but sometimes
for either simplicity, or perhaps for the environment you are deploying to (Android),
you just want to use a good old-fashioned <code>HttpURLConnection</code>.  This library seeks
to add convenience and common patterns to the act of making HTTP requests such as
a fluid-interface for building requests and support for features such as multipart
requests.</p>

<p><strong>Bottom line:</strong> The single goal of this library is to improve the usability of the
<code>HttpURLConnection</code> class.</p>

<h3>
<a name="what-are-the-dependencies" class="anchor" href="#what-are-the-dependencies"><span class="octicon octicon-link"></span></a>What are the dependencies?</h3>

<p>None.  The goal of this library is to be a single class class with some inner static
classes.  The test project does require <a href="http://eclipse.org/jetty/">Jetty</a> in order
to test requests against an actual HTTP server implementation.</p>

<h3>
<a name="how-are-exceptions-managed" class="anchor" href="#how-are-exceptions-managed"><span class="octicon octicon-link"></span></a>How are exceptions managed?</h3>

<p>The <code>HttpRequest</code> class does not throw any checked exceptions, instead all low-level
exceptions are wrapped up in a <code>HttpRequestException</code> which extends <code>RuntimeException</code>.
You can access the underlying exception by catching <code>HttpRequestException</code> and calling
<code>getCause()</code> which will always return the original <code>IOException</code>.</p>

<h2>
<a name="examples" class="anchor" href="#examples"><span class="octicon octicon-link"></span></a>Examples</h2>

<h3>
<a name="perform-a-get-request-and-get-the-status-of-the-response" class="anchor" href="#perform-a-get-request-and-get-the-status-of-the-response"><span class="octicon octicon-link"></span></a>Perform a GET request and get the status of the response</h3>

<div class="highlight"><pre><span class="kt">int</span> <span class="n">response</span> <span class="o">=</span> <span class="n">HttpRequest</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">"http://google.com"</span><span class="o">).</span><span class="na">code</span><span class="o">();</span>
</pre></div>

<h3>
<a name="perform-a-get-request-and-get-the-body-of-the-response" class="anchor" href="#perform-a-get-request-and-get-the-body-of-the-response"><span class="octicon octicon-link"></span></a>Perform a GET request and get the body of the response</h3>

<div class="highlight"><pre><span class="n">String</span> <span class="n">response</span> <span class="o">=</span> <span class="n">HttpRequest</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">"http://google.com"</span><span class="o">).</span><span class="na">body</span><span class="o">();</span>
<span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Response was: "</span> <span class="o">+</span> <span class="n">response</span><span class="o">);</span>
</pre></div>

<h3>
<a name="print-the-response-of-a-get-request-to-standard-out" class="anchor" href="#print-the-response-of-a-get-request-to-standard-out"><span class="octicon octicon-link"></span></a>Print the response of a GET request to standard out</h3>

<div class="highlight"><pre><span class="n">HttpRequest</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">"http://google.com"</span><span class="o">).</span><span class="na">receive</span><span class="o">(</span><span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">);</span>
</pre></div>

<h3>
<a name="adding-query-parameters" class="anchor" href="#adding-query-parameters"><span class="octicon octicon-link"></span></a>Adding query parameters</h3>

<div class="highlight"><pre><span class="n">HttpRequest</span> <span class="n">request</span> <span class="o">=</span> <span class="n">HttpRequest</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">"http://google.com"</span><span class="o">,</span> <span class="kc">true</span><span class="o">,</span> <span class="sc">'q'</span><span class="o">,</span> <span class="s">"baseball gloves"</span><span class="o">,</span> <span class="s">"size"</span><span class="o">,</span> <span class="mi">100</span><span class="o">);</span>
<span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="n">request</span><span class="o">.</span><span class="na">toString</span><span class="o">());</span> <span class="c1">// GET http://google.com?q=baseball%20gloves&amp;size=100</span>
</pre></div>

<h3>
<a name="working-with-requestresponse-headers" class="anchor" href="#working-with-requestresponse-headers"><span class="octicon octicon-link"></span></a>Working with request/response headers</h3>

<div class="highlight"><pre><span class="n">String</span> <span class="n">contentType</span> <span class="o">=</span> <span class="n">HttpRequest</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">"http://google.com"</span><span class="o">)</span>
                                <span class="o">.</span><span class="na">accept</span><span class="o">(</span><span class="s">"application/json"</span><span class="o">)</span> <span class="c1">//Sets request header</span>
                                <span class="o">.</span><span class="na">contentType</span><span class="o">();</span> <span class="c1">//Gets response header</span>
<span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Response content type was "</span> <span class="o">+</span> <span class="n">contentType</span><span class="o">);</span>
</pre></div>

<h3>
<a name="perform-a-post-request-with-some-data-and-get-the-status-of-the-response" class="anchor" href="#perform-a-post-request-with-some-data-and-get-the-status-of-the-response"><span class="octicon octicon-link"></span></a>Perform a POST request with some data and get the status of the response</h3>

<div class="highlight"><pre><span class="kt">int</span> <span class="n">response</span> <span class="o">=</span> <span class="n">HttpRequest</span><span class="o">.</span><span class="na">post</span><span class="o">(</span><span class="s">"http://google.com"</span><span class="o">).</span><span class="na">send</span><span class="o">(</span><span class="s">"name=kevin"</span><span class="o">).</span><span class="na">code</span><span class="o">();</span>
</pre></div>

<h3>
<a name="authenticate-using-basic-authentication" class="anchor" href="#authenticate-using-basic-authentication"><span class="octicon octicon-link"></span></a>Authenticate using Basic authentication</h3>

<div class="highlight"><pre><span class="kt">int</span> <span class="n">response</span> <span class="o">=</span> <span class="n">HttpRequest</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">"http://google.com"</span><span class="o">).</span><span class="na">basic</span><span class="o">(</span><span class="s">"username"</span><span class="o">,</span> <span class="s">"p4ssw0rd"</span><span class="o">).</span><span class="na">code</span><span class="o">();</span>
</pre></div>

<h3>
<a name="perform-a-multipart-post-request" class="anchor" href="#perform-a-multipart-post-request"><span class="octicon octicon-link"></span></a>Perform a multipart POST request</h3>

<div class="highlight"><pre><span class="n">HttpRequest</span> <span class="n">request</span> <span class="o">=</span> <span class="n">HttpRequest</span><span class="o">.</span><span class="na">post</span><span class="o">(</span><span class="s">"http://google.com"</span><span class="o">);</span>
<span class="n">request</span><span class="o">.</span><span class="na">part</span><span class="o">(</span><span class="s">"status[body]"</span><span class="o">,</span> <span class="s">"Making a multipart request"</span><span class="o">);</span>
<span class="n">request</span><span class="o">.</span><span class="na">part</span><span class="o">(</span><span class="s">"status[image]"</span><span class="o">,</span> <span class="k">new</span> <span class="n">File</span><span class="o">(</span><span class="s">"/home/kevin/Pictures/ide.png"</span><span class="o">));</span>
<span class="k">if</span> <span class="o">(</span><span class="n">request</span><span class="o">.</span><span class="na">ok</span><span class="o">())</span>
  <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Status was updated"</span><span class="o">);</span>
</pre></div>

<h3>
<a name="perform-a-post-request-with-form-data" class="anchor" href="#perform-a-post-request-with-form-data"><span class="octicon octicon-link"></span></a>Perform a POST request with form data</h3>

<div class="highlight"><pre><span class="n">Map</span><span class="o">&lt;</span><span class="n">String</span><span class="o">,</span> <span class="n">String</span><span class="o">&gt;</span> <span class="n">data</span> <span class="o">=</span> <span class="k">new</span> <span class="n">HashMap</span><span class="o">&lt;</span><span class="n">String</span><span class="o">,</span> <span class="n">String</span><span class="o">&gt;();</span>
<span class="n">data</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"user"</span><span class="o">,</span> <span class="s">"A User"</span><span class="o">);</span>
<span class="n">data</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"state"</span><span class="o">,</span> <span class="s">"CA"</span><span class="o">);</span>
<span class="k">if</span> <span class="o">(</span><span class="n">HttpRequest</span><span class="o">.</span><span class="na">post</span><span class="o">(</span><span class="s">"http://google.com"</span><span class="o">).</span><span class="na">form</span><span class="o">(</span><span class="n">data</span><span class="o">).</span><span class="na">created</span><span class="o">())</span>
  <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"User was created"</span><span class="o">);</span>
</pre></div>

<h3>
<a name="copy-body-of-response-to-a-file" class="anchor" href="#copy-body-of-response-to-a-file"><span class="octicon octicon-link"></span></a>Copy body of response to a file</h3>

<div class="highlight"><pre><span class="n">File</span> <span class="n">output</span> <span class="o">=</span> <span class="k">new</span> <span class="n">File</span><span class="o">(</span><span class="s">"/output/request.out"</span><span class="o">);</span>
<span class="n">HttpRequest</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">"http://google.com"</span><span class="o">).</span><span class="na">receive</span><span class="o">(</span><span class="n">output</span><span class="o">);</span>
</pre></div>

<h3>
<a name="post-contents-of-a-file" class="anchor" href="#post-contents-of-a-file"><span class="octicon octicon-link"></span></a>Post contents of a file</h3>

<div class="highlight"><pre><span class="n">File</span> <span class="n">input</span> <span class="o">=</span> <span class="k">new</span> <span class="n">File</span><span class="o">(</span><span class="s">"/input/data.txt"</span><span class="o">);</span>
<span class="kt">int</span> <span class="n">response</span> <span class="o">=</span> <span class="n">HttpRequest</span><span class="o">.</span><span class="na">post</span><span class="o">(</span><span class="s">"http://google.com"</span><span class="o">).</span><span class="na">send</span><span class="o">(</span><span class="n">input</span><span class="o">).</span><span class="na">code</span><span class="o">();</span>
</pre></div>

<h3>
<a name="using-entity-tags-for-caching" class="anchor" href="#using-entity-tags-for-caching"><span class="octicon octicon-link"></span></a>Using entity tags for caching</h3>

<div class="highlight"><pre><span class="n">File</span> <span class="n">latest</span> <span class="o">=</span> <span class="k">new</span> <span class="n">File</span><span class="o">(</span><span class="s">"/data/cache.json"</span><span class="o">);</span>
<span class="n">HttpRequest</span> <span class="n">request</span> <span class="o">=</span> <span class="n">HttpRequest</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">"http://google.com"</span><span class="o">);</span>
<span class="c1">//Copy response to file</span>
<span class="n">request</span><span class="o">.</span><span class="na">receive</span><span class="o">(</span><span class="n">latest</span><span class="o">);</span>
<span class="c1">//Store eTag of response</span>
<span class="n">String</span> <span class="n">eTag</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="na">eTag</span><span class="o">();</span>
<span class="c1">//Later on check if changes exist</span>
<span class="kt">boolean</span> <span class="n">unchanged</span> <span class="o">=</span> <span class="n">HttpRequest</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">"http://google.com"</span><span class="o">)</span>
                               <span class="o">.</span><span class="na">ifNoneMatch</span><span class="o">(</span><span class="n">eTag</span><span class="o">)</span>
                               <span class="o">.</span><span class="na">notModified</span><span class="o">();</span>
</pre></div>

<h3>
<a name="using-gzip-compression" class="anchor" href="#using-gzip-compression"><span class="octicon octicon-link"></span></a>Using gzip compression</h3>

<div class="highlight"><pre><span class="n">HttpRequest</span> <span class="n">request</span> <span class="o">=</span> <span class="n">HttpRequest</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">"http://google.com"</span><span class="o">);</span>
<span class="c1">//Tell server to gzip response and automatically uncompress</span>
<span class="n">request</span><span class="o">.</span><span class="na">acceptGzipEncoding</span><span class="o">().</span><span class="na">uncompress</span><span class="o">(</span><span class="kc">true</span><span class="o">);</span>
<span class="n">String</span> <span class="n">uncompressed</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="na">body</span><span class="o">();</span>
<span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Uncompressed response is: "</span> <span class="o">+</span> <span class="n">uncompressed</span><span class="o">);</span>
</pre></div>

<h3>
<a name="ignoring-security-when-using-https" class="anchor" href="#ignoring-security-when-using-https"><span class="octicon octicon-link"></span></a>Ignoring security when using HTTPS</h3>

<div class="highlight"><pre><span class="n">HttpRequest</span> <span class="n">request</span> <span class="o">=</span> <span class="n">HttpRequest</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">"https://google.com"</span><span class="o">);</span>
<span class="c1">//Accept all certificates</span>
<span class="n">request</span><span class="o">.</span><span class="na">trustAllCerts</span><span class="o">();</span>
<span class="c1">//Accept all hostnames</span>
<span class="n">request</span><span class="o">.</span><span class="na">trustAllHosts</span><span class="o">();</span>
</pre></div>

<h3>
<a name="configure-http-proxy" class="anchor" href="#configure-http-proxy"><span class="octicon octicon-link"></span></a>Configure HTTP proxy</h3>

<div class="highlight"><pre><span class="n">HttpRequest</span> <span class="n">request</span> <span class="o">=</span> <span class="n">HttpRequest</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">"https://google.com"</span><span class="o">);</span>
<span class="c1">//Configure proxy</span>
<span class="n">request</span><span class="o">.</span><span class="na">useProxy</span><span class="o">(</span><span class="s">"localhost"</span><span class="o">,</span> <span class="mi">8080</span><span class="o">);</span>
<span class="c1">//Optional proxy basic uthentication</span>
<span class="n">request</span><span class="o">.</span><span class="na">proxyBasic</span><span class="o">(</span><span class="s">"username"</span><span class="o">,</span> <span class="s">"p4ssw0rd"</span><span class="o">);</span>
</pre></div>

<h3>
<a name="follow-redirects" class="anchor" href="#follow-redirects"><span class="octicon octicon-link"></span></a>Follow redirects</h3>

<div class="highlight"><pre><span class="kt">int</span> <span class="n">code</span> <span class="o">=</span> <span class="n">HttpRequest</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">"http://google.com"</span><span class="o">).</span><span class="na">followRedirects</span><span class="o">(</span><span class="kc">true</span><span class="o">).</span><span class="na">code</span><span class="o">();</span>
</pre></div>

<h3>
<a name="custom-connection-factory" class="anchor" href="#custom-connection-factory"><span class="octicon octicon-link"></span></a>Custom connection factory</h3>

<div class="highlight"><pre><span class="n">HttpRequest</span><span class="o">.</span><span class="na">setConnectionFactory</span><span class="o">(</span><span class="k">new</span> <span class="n">ConnectionFactory</span><span class="o">()</span> <span class="o">{</span>

  <span class="kd">public</span> <span class="n">HttpURLConnection</span> <span class="nf">create</span><span class="o">(</span><span class="n">URL</span> <span class="n">url</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">IOException</span> <span class="o">{</span>
    <span class="k">if</span> <span class="o">(!</span><span class="s">"https"</span><span class="o">.</span><span class="na">equals</span><span class="o">(</span><span class="n">url</span><span class="o">.</span><span class="na">getProtocol</span><span class="o">()))</span> <span class="o">{</span>
      <span class="k">throw</span> <span class="k">new</span> <span class="nf">IOException</span><span class="o">(</span><span class="s">"Only secure requests are allowed"</span><span class="o">);</span>
    <span class="o">}</span>
    <span class="k">return</span> <span class="o">(</span><span class="n">HttpURLConnection</span><span class="o">)</span> <span class="n">url</span><span class="o">.</span><span class="na">openConnection</span><span class="o">();</span>
  <span class="o">}</span>

  <span class="kd">public</span> <span class="n">HttpURLConnection</span> <span class="nf">create</span><span class="o">(</span><span class="n">URL</span> <span class="n">url</span><span class="o">,</span> <span class="n">Proxy</span> <span class="n">proxy</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">IOException</span> <span class="o">{</span>
    <span class="k">if</span> <span class="o">(!</span><span class="s">"https"</span><span class="o">.</span><span class="na">equals</span><span class="o">(</span><span class="n">url</span><span class="o">.</span><span class="na">getProtocol</span><span class="o">()))</span> <span class="o">{</span>
      <span class="k">throw</span> <span class="k">new</span> <span class="nf">IOException</span><span class="o">(</span><span class="s">"Only secure requests are allowed"</span><span class="o">);</span>
    <span class="o">}</span>
    <span class="k">return</span> <span class="o">(</span><span class="n">HttpURLConnection</span><span class="o">)</span> <span class="n">url</span><span class="o">.</span><span class="na">openConnection</span><span class="o">(</span><span class="n">proxy</span><span class="o">);</span>
  <span class="o">}</span>
<span class="o">});</span>
</pre></div>

<h2>
<a name="contributors" class="anchor" href="#contributors"><span class="octicon octicon-link"></span></a>Contributors</h2>

<ul>
<li>
<a href="https://github.com/kevinsawicki">Kevin Sawicki</a> :: <a href="https://github.com/kevinsawicki/http-request/commits?author=kevinsawicki">contributions</a>
</li>
<li>
<a href="https://github.com/eddieringle">Eddie Ringle</a> :: <a href="https://github.com/kevinsawicki/http-request/commits?author=eddieringle">contributions</a>
</li>
<li>
<a href="https://github.com/seanjensengrey">Sean Jensen-Grey</a> :: <a href="https://github.com/kevinsawicki/http-request/commits?author=seanjensengrey">contributions</a>
</li>
<li>
<a href="https://github.com/levinotik">Levi Notik</a> :: <a href="https://github.com/kevinsawicki/http-request/commits?author=levinotik">contributions</a>
</li>
<li>
<a href="https://github.com/michael-wang">Michael Wang</a> :: <a href="https://github.com/kevinsawicki/http-request/commits?author=michael-wang">contributions</a>
</li>
<li>
<a href="https://github.com/henryju">Julien HENRY</a> :: <a href="https://github.com/kevinsawicki/http-request/commits?author=henryju">contributions</a>
</li>
<li>
<a href="https://github.com/BoD">Benoit Lubek</a> :: <a href="https://github.com/kevinsawicki/http-request/commits?author=BoD">contributions</a>
</li>
<li>
<a href="https://github.com/JakeWharton">Jake Wharton</a> :: <a href="https://github.com/kevinsawicki/http-request/commits?author=JakeWharton">contributions</a>
</li>
</ul>
      </section>
    </div>

    <!-- FOOTER  -->
    <div id="footer_wrap" class="outer">
      <footer class="inner">
        <p class="copyright">http-request maintained by <a href="https://github.com/kevinsawicki">kevinsawicki</a></p>
        <p>Published with <a href="http://pages.github.com">GitHub Pages</a></p>
      </footer>
    </div>



  </body>
</html>
